CI Login Token Exchange: Long-Lived Refresh Tokens for Headless Auth

Summary

Adds support for long-lived organization-scoped refresh tokens for headless CI/CD pipelines. Users can provision a token once (interactive) and use it in CI without running hd auth login in the pipeline.

Updates (Provision orgId from User Setup): Provision no longer requires --org-id; orgId is obtained from the user setup API. The hd auth-ci login command has been removed—scans exchange the CI token for an access token automatically via requireAccessTokenForScan.

Design

Flow

sequenceDiagram
    participant User
    participant Login
    participant Provision
    participant UserSetup
    participant Scan

    User->>Login: hd auth login
    Login->>Login: OAuth PKCE, persist tokens (keyring)

    User->>Provision: hd auth-ci provision
    Provision->>UserSetup: getUserSetupStatus / completeUserSetup
    UserSetup-->>Provision: orgId
    Provision->>IAM: getOrgAccessTokens(orgId, null) [Bearer from login]
    IAM-->>Provision: refreshToken (long-lived)
    Provision->>Provision: saveCIToken, saveCIOrgId

    Note over User: CI pipeline runs (headless)
    User->>Scan: hd scan eol (HD_AUTH_TOKEN, HD_ORG_ID set)
    Scan->>Scan: requireAccessTokenForScan → requireCIAccessToken
    Scan->>IAM: getOrgAccessTokens(orgId, refreshToken)
    IAM-->>Scan: accessToken, refreshToken (maybe rotated)
    Scan->>Scan: uses accessToken for API calls

Auth Resolution Order

requireAccessTokenForScan (used by scan, Apollo default, completeUserSetup) now:

1. CI first: If getCIToken() or config.accessTokenFromEnv → use CI path (requireCIAccessToken)
2. Keyring second: Else use stored OAuth tokens (keyring) with refresh via Keycloak

CI tokens come from:

• Env (CI): HD_AUTH_TOKEN, HD_ORG_ID, HD_ACCESS_TOKEN
• File (local): ~/.hdcli/ci-token (encrypted, machine-bound)

Prerequisites

• eol-api PR feat: analytics #301 must be merged before deploying these CLI changes. The new UserSetupStatus schema ({ isComplete, orgId }) is required.

Changes

Commands

Removed: hd auth-ci login — redundant. Scans call requireAccessTokenForScan → requireCIAccessToken, which exchanges the CI token internally.

New / Updated Files

• src/commands/auth-ci/provision.ts – CI provision (no --org-id; uses ensureUserSetup for orgId)
• src/api/user-setup.client.ts – getUserSetupStatus and completeUserSetup return { isComplete, orgId }; ensureUserSetup returns orgId
• src/api/gql-operations.ts – userSetupStatusQuery and completeUserSetupMutation use UserSetupStatus object schema
• src/service/ci-auth.svc.ts – CI auth path; error messages updated (no --org-id references)
• src/service/ci-token.svc.ts – CI token storage (env + encrypted file via conf); saveCIOrgId / getCIOrgId for org persistence
• src/api/ci-token.client.ts – IAM getOrgAccessTokens client (provisionCIToken, exchangeCITokenForAccess)
• src/api/apollo.client.ts – Extracted from nes.client.ts; shared Apollo factory with token provider
• src/config/constants.ts – Added ENABLE_AUTH, ENABLE_USER_SETUP, ciTokenFromEnv, orgIdFromEnv, accessTokenFromEnv, IAM config
• src/service/auth.svc.ts – requireAccessTokenForScan delegates to CI path first, re-exports CITokenError

README

• CI/CD authentication section updated with new flow
• One-time setup: hd auth login → hd auth-ci provision (no --org-id)
• CI pipeline: hd scan eol directly with HD_AUTH_TOKEN and HD_ORG_ID (no eval step)
• GitHub Actions and GitLab CI examples updated

Other

• nes.client.ts: Uses shared createApollo from apollo.client.ts
• user-setup.client.ts: completeUserSetup uses requireAccessTokenForScan; ensureUserSetup extended to return orgId for provision

Usage

One-time setup (interactive):

hd auth login
hd auth-ci provision

Copy token output into CI secrets: HD_AUTH_TOKEN, HD_ORG_ID (orgId also stored at provision time when using local file).

CI pipeline:

export HD_ORG_ID=<id> HD_AUTH_TOKEN="<token>"
hd scan eol --dir .

Gaps & Follow-ups